docs: scope policy guidance in MCP instructions, README, and ADRs 0021/0022 by 5queezer · Pull Request #3 · 5queezer/aver

5queezer · 2026-07-18T10:59:19Z

Commits the previously-uncommitted working tree changes:

mcp.rs: adds a scope-policy sentence to the MCP tool instructions card — pass scope only as an explicit per-call override, otherwise the ADR-0022 resolved scope applies; scope_walk=ancestors for normal project memory, exact for isolation, descendants for subtree audits, any only for cross-scope search.
scope_resolution.rs: fixes stale migration reference in comment (0084 → 0085).
README: documents ADR-0021/0022 scoped memory parameters and scope_walk usage; notes vector chunks inherit their claim's scope.
ADR 0021/0022: content updates to match implementation.
mcp_instructions.rs: pins the new instruction text.
autoresearch.jsonl: appends run logs 539–540.

Verified: cargo test -p aver-server --test mcp_instructions green, cargo fmt --check clean.

Summary by CodeRabbit

Documentation
- Finalized “scope as a first-class memory dimension” with clear rules for defaults vs per-call overrides, vector scope inheritance, and read traversal modes (ancestors/exact/descendants/any).
- Updated MCP instructions and connection scope-resolution behavior, plus corrected migration references.
Improvements
- Strengthened ontology extension validation to prevent self-parenting extensions.
- Improved/clarified scope value validation to match the correct enforcement rule.

…1/0022 - mcp.rs: add scope policy sentence (explicit override vs resolved scope, scope_walk semantics) to the MCP tool instructions card - scope_resolution.rs: fix stale migration reference 0084 -> 0085 - README: document ADR-0021/0022 scoped memory parameters and scope_walk usage - ADR 0021/0022: content updates to match implementation - mcp_instructions.rs: pin the new instruction text - autoresearch.jsonl: append run logs 539-540

coderabbitai · 2026-07-18T10:59:33Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e2da1314-ee32-44da-820a-deeb35369b0f

📥 Commits

Reviewing files that changed from the base of the PR and between 510b907 and c5b8704.

📒 Files selected for processing (3)

README.md
doc/adr/0021-scope-as-first-class-memory-dimension.md
doc/adr/0022-connection-scope-resolution.md

📝 Walkthrough

Walkthrough

The PR finalizes scope-related ADRs, expands README and MCP guidance, updates instruction tests, corrects a migration reference, and records two schema-hardening experiments, including one failed legacy migration replay.

Changes

Scope contract alignment

Layer / File(s)	Summary
Memory scope schema and write semantics `doc/adr/0021-scope-as-first-class-memory-dimension.md`	Documents scoped columns, indexes, candidate promotion, path-derived scopes, and claim-inherited vector scope.
Connection resolution and audit provenance `doc/adr/0022-connection-scope-resolution.md`, `crates/aver-server/src/scope_resolution.rs`	Updates ADR status, episodic-event audit references, absolute-path fallback hashing, and the migration citation.
MCP scope discovery guidance `README.md`, `crates/aver-server/src/mcp.rs`, `crates/aver-server/tests/mcp_instructions.rs`	Describes scope overrides, defaults, and `scope_walk` modes in documentation and progressive-discovery tests.
Schema experiment records `autoresearch.jsonl`	Records ontology self-parenting checks and a failed `created_via` trigger during legacy migration replay.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

5queezer/aver#1: Touches the same MCP instruction generation and verification paths.
5queezer/aver#7: Overlaps the MCP and scope-resolution changes in the server.

Poem

Scope walks the memory halls,
Ancestors rise, descendants call.
Claims hold vectors close and true,
Logs record the path they knew.
One trigger fell; the checks stand guard.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main documentation-focused scope policy updates across MCP instructions, README, and ADRs 0021/0022.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/scope-policy-and-adr-accuracy

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@doc/adr/0021-scope-as-first-class-memory-dimension.md`:
- Around line 78-97: Update the consequences section of the ADR to state that
the migration adds four scope indexes, including candidate_claims_scope, instead
of three. Keep the surrounding cost discussion unchanged.

In `@doc/adr/0022-connection-scope-resolution.md`:
- Around line 214-217: The scope fallback documentation is inconsistent across
layers. In doc/adr/0022-connection-scope-resolution.md lines 214-217, align the
origin-less repository fallback with ADR-0021’s canonical behavior instead of
documenting a conflicting absolute-worktree-root hash rule; in README.md lines
222-223, document that AVER_DEFAULT_SCOPE is checked before falling back to the
hardcoded global scope.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a553a094-9c1f-4e67-9ec2-b2e76414e62e

📥 Commits

Reviewing files that changed from the base of the PR and between f84fd7e and 510b907.

📒 Files selected for processing (7)

README.md
autoresearch.jsonl
crates/aver-server/src/mcp.rs
crates/aver-server/src/scope_resolution.rs
crates/aver-server/tests/mcp_instructions.rs
doc/adr/0021-scope-as-first-class-memory-dimension.md
doc/adr/0022-connection-scope-resolution.md

coderabbitai · 2026-07-18T11:02:50Z

+  without an origin (fresh clones, local-only experiments) fall back to hashing
+  the absolute worktree root. That avoids basename collisions but means moving a
+  local-only repository changes its derived scope. Mitigation:
+  `AVER_DEFAULT_SCOPE` override; explicit `--scope` flag on the shim.


🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Align the documented scope fallback contract across layers.

The current documentation gives clients conflicting expectations about how scopes are derived when no explicit per-call scope is supplied. Canonicalize both the origin-less repository fallback and the configured environment fallback.

doc/adr/0022-connection-scope-resolution.md#L214-L217: reconcile the absolute-path hash rule with ADR-0021’s origin-less fallback.

README.md#L222-L223: document that AVER_DEFAULT_SCOPE is checked before the hardcoded global fallback.

📍 Affects 2 files

doc/adr/0022-connection-scope-resolution.md#L214-L217 (this comment)

README.md#L222-L223

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@doc/adr/0022-connection-scope-resolution.md` around lines 214 - 217, The scope fallback documentation is inconsistent across layers. In doc/adr/0022-connection-scope-resolution.md lines 214-217, align the origin-less repository fallback with ADR-0021’s canonical behavior instead of documenting a conflicting absolute-worktree-root hash rule; in README.md lines 222-223, document that AVER_DEFAULT_SCOPE is checked before falling back to the hardcoded global scope.

5queezer · 2026-07-27T12:26:09Z

Addressed the two review findings in c5b8704: corrected the ADR-0021 scope-index count and aligned the origin-less worktree hash plus AVER_DEFAULT_SCOPE → global fallback contract across ADR-0021/0022 and README.

Validation: cargo +1.95.0 fmt --all -- --check; cargo +1.95.0 test -p aver-server --test mcp_instructions (2 passed).

— Hermes Agent

coderabbitai Bot reviewed Jul 18, 2026

View reviewed changes

5queezer and others added 2 commits July 18, 2026 13:05

docs(adr): mark 0021 and 0022 as Accepted (implemented)

c989c27

docs: align scope fallback and schema cost

c5b8704

5queezer merged commit dd4f3c6 into master Jul 27, 2026
2 of 3 checks passed

5queezer deleted the docs/scope-policy-and-adr-accuracy branch July 27, 2026 12:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: scope policy guidance in MCP instructions, README, and ADRs 0021/0022#3

docs: scope policy guidance in MCP instructions, README, and ADRs 0021/0022#3
5queezer merged 3 commits into
masterfrom
docs/scope-policy-and-adr-accuracy

5queezer commented Jul 18, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 18, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot Jul 18, 2026

Uh oh!

5queezer commented Jul 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

5queezer commented Jul 18, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

5queezer commented Jul 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

5queezer commented Jul 18, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 18, 2026 •

edited

Loading